SFXpolyDump
By Fenix (Fenix Eldritch)
Version 1.6.1
2021-12-20

A Java command line utility which can dump/export the 3D model data from various Argonaut SuperFX SNES games into a modern .obj format. Color data will be exported as a shared .mtl file and individual textures are also exported as .png files.

Basic usage:	java SFXpolyDump -rom <romfile>

This utility primarily works with unmodified roms which do not contain a dumper header. However, it can recognize 2020 Gigaleak roms which have had their internal headers fixed to run on emulators using the ips patch from tcrf.net:
https://tcrf.net/File:Star_Fox_2_(Beta_Header_Patch).zip

Static models, the shared MasterPalette.mtl file, and textures are placed in a combined folder upon export. Animated models are placed in sub-directories and each frame is exported as its own full model. The .mtl file and textures are also duplicated to the animated model subdirectories as needed.

Models are named by a combination of their object ID and vertex list address in ROM.

When importing the dumped models into another 3D program like Blender, use -Z Forward and -Y Up.

Some models are entirely wireframe.

Some models have mistakes in the original roms. Where possible, this utility attempts to correct known or obvious mistakes on the fly during export. Look for the keyword "hack" in the logfile.


Defaults:
---------

By default the utility will export models and textures using pre-set palettes. You can force the use of alternate palettes by using the optional parameters -mp and -tp as described in the usage message.

The utility will also export animated surfaces with the first frame of that animation (color/texture). You can force the dumping of all animated texture frames with the -df option.

The utility will attempt to export all known models in a given rom. However, you can specify an individual model to target by using the -hdr option. You must supply the hex address (without the "0x" prefix) of the object's header. You can get this header address by referencing the logfile produced after running the utility normally.


Limitations:
------------

A number of models from StarFox1 will fail to export. These are of type $50 and are believed to be 2D sprites. You can view all bit-mapped textures in the "SFXpolyDump IMG.png" image.

At present, the utility does not properly support StuntRaceFX roms. It can dump all models' geometry, but the palette data is not fully understood and gets exported incorrectly. This includes the coloring of texture data as well. Future versions hope to correct this.

The StarFox1 prototype (SG.ROM) is also not fully supported yet. Surfaces which have animated materials are not fully understood (they behave differently from StarFox) and as such are exported incorrectly. Future versions hope to correct this.

Later builds of StarFox2 (from SF2 CES onward) contain two texture offset tables and there does not appear to be a way to discern which one to use from the model data alone. This only seems to impact two models (Pepper Coin and Pierrot Platform) which will export with seemingly "wrong" textures. This can be remedied by exporting with the -at option for those models.


Usage printout:
---------------

SFXpolyDump - Given an Argonaut SuperFX rom, dump models, palette, and textures
              Version: 1.6.0, by Fenix 2012-2021

Usage: java SFXpolyDump -rom <romfile>
       [-mp <x>] [-tp <y>] [-ls <z>] [-hdr <address>] [-df] [-at] [-?]

Required parms:
 -rom <romfile>   Specify an Argonaut SuperFX rom. See list for valid CRC32s.

Optional parms:
 -hdr <address>   Header address override.  (process single object)
 -mp <x>          Model palette override.   (see Pal column below)
 -tp <y>          Texture palette override. (see Pal column below)
 -ls <z>          Light source index override. (default: 4, range: 0-9)
 -df              Dump all animated material frames.  (instead of 1st)
 -at              Use alternate texture offset table. (if applicable)
 -?               Print this usage message.

Use unmodified roms without a dumper header.
SF2 roms patched with tcrf.net's header fix (21:47 15-11-2020) also work.

 CRC32     Rom                   Date        Pal  Patched-CRC32
----------------------------------------------------------------------
 24010748  StarGlider Proto      1992-09-24  n/a  3483156A  (W.I.P.)
 41A60B3F  StarFox  v1.0 JP      n/a         0-2  n/a
 0BAE0941  StarFox  v1.0 USA     n/a         0-2  n/a
 8FC4E6D0  StarFox  v1.2 USA     n/a         0-2  n/a
 B48CA238  StarWing v1.0 G       n/a         0-2  n/a
 865F1A71  StarWing v1.0 EU      n/a         0-2  n/a
 BA64DA2B  StarWing v1.1 EU      n/a         0-2  n/a
 40946E9B  StarFox2 Alpha        1994-04-01  n/a  n/a
 70D7AD50  StarFox2 Alpha        1994-04-15  n/a  n/a
 52018C77  StarFox2 Alpha        1994-05-06  n/a  n/a
 D8B14E9D  StarFox2 Alpha        1994-05-13  n/a  n/a
 D0FCF5F5  StarFox2 Alpha        1994-08-31  0-3  n/a
 B1439CBA  StarFox2 CES          1994-12-28  0-3  74F8AC20
 38B87495  StarFox2 Beta         1995-06-08  0-5  58F9D2E1
 79F3433D  StarFox2 Beta         1995-06-22  0-5  n/a
 87653732  StarFox2 Final USA    1995-09-12  0-4  n/a
 B019AE0B  StarFox2 Kawa-debug   1995-09-13  0-4  A847A8F4
 31B1AD00  Vortex   v1.0 USA     n/a         0-3  n/a
 F1F0DA37  StuntRaceFX Proto     n/a         n/a  n/a       (W.I.P.)
 24935769  StuntRaceFX v1.0 EU   n/a         n/a  n/a       (W.I.P.)
 380C2635  StuntRaceFX v1.1 USA  n/a         0-14 n/a       (W.I.P.)


History:
--------
2012-12-13 v1.0.0 Initial version (Can dump SF1/SF2 models only, no colors/textures)
2020-08-30 v1.1.0 Improved version (Supports newly found SF2 roms and color/textures!)
2020-10-29 v1.2.0 Added support for SF1 proto. Fixed Vortex support. Basic SRFX support.
2021-04-30 v1.5.0 Various small fixes & tweaks, initial release to RHDN.
2021-05-03 v1.6.0 Copy mtl/png to animated subdirs. Updated SF1 default palette selection.
2021-12-20 v1.6.1 Corrected color mixing in .mtl file. Added light source override option.
